<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8">
	<title>Coding Standards - Fuel Documentation</title>
	<link href="../assets/css/main.css" media="screen" rel="stylesheet" />
	<script type="text/javascript" src="../assets/js/jquery-1.4.4.min.js"></script>
	<script type="text/javascript" src="../assets/js/nav.js"></script>
	<script type="text/javascript" src="../assets/js/highlight.pack.js"></script>
	<script type="text/javascript">
		$(function() {
			show_nav('general', '../');
		});
		hljs.tabReplace = '    ';
		hljs.initHighlightingOnLoad();
	</script>
</head>
<body>

	<header>
		<h1>Fuel Documentation</h1>
	</header>

	<div id="main-nav"></div>

	<section id="content">
		<h2>Coding Standards</h2>

		<p>These standards for code formatting and documentation must be followed by anyone contributing to Fuel. Any
			contributions that do not meet these guidelines will not be accepted.</p>

		<h3 id="file_formatting">File Formatting</h3>

		<h5 id="closing_php_tag">Closing PHP Tag</h5>

		<p>Files containing only PHP code should always omit the closing PHP tag (?>). This prevents many of the
			elusive white screens of death. You should put a comment at the bottom of the file though:</p>

<pre class="php"><code>/* End of file filename.php */</code></pre>

		<h5 id="indentation">Indentation</h5>

		<p>All indentation should be done using real tabs, NOT spaces.<br />
			But aligning things after the indentation should be done using spaces, NOT tabs.</p>

<pre class="php"><code>		// indented 2 tabs
		$var       = 'something';  // indented with tabs and aligned value &amp; comments
		$variable  = 'else';       // with those above/below using spaces</code></pre>

		<h5 id="line_endings">Line Endings</h5>

		<p>Line endings should be Unix-style LF.</p>

		<h5 id="file_naming">File Naming</h5>

		<p>All file names must be all lower case. No exceptions.</p>

		<h5 id="encoding">Encoding</h5>

		<p>Files should be saved with UTF-8 encoding and the BOM should not be used.</p>

		<h3 id="naming_conventions">Naming Conventions</h3>

		<h5 id="namespaces">Namespaces</h5>

		<p>All core classes must be under the Fuel\Core namespace.</p>

<pre class="php"><code>namespace Fuel\Core;</code></pre>

		<h5 id="classes">Classes</h5>

		<p>Class names should use underscores to separate words, and each word in the class name should begin with a
			capital letter. An underscore will however be converted to a directory separator during autoloading, the
			use of camelcase is discouraged but cannot be prevented in some cases when putting the class in a
			subdirectory makes no sense.</p>

<pre class="php"><code>namespace Fuel\Core;

// ------------------------------------------------------------------------

class Session {

}</code></pre>

<pre class="php"><code>namespace Fuel\Core;

// ------------------------------------------------------------------------

class Session_Cookie extends Session_Driver {

}</code></pre>

		<p>This would result in the following file path:</p>

<pre class="php"><code>core/classes/session.php
core/classes/session/cookie.php</code></pre>

		<h5 id="methods">Methods</h5>

		<p>Like class names, method names should use underscores to separate words, not CamelCase. Method names should
			also be all lower case. Visibility should always be included (public, protected, private).<br />
			An underscore can be used at the beginning of the name to make it clear the method is protected/private, or
			to signify it should be considered as such when you need it public.</p>

<pre class="php"><code>class Session {

	public static function get_flash($name, $data)
	{
		// Some code here
	}

}</code></pre>

<pre class="php"><code>class View {

	// Array of global view data
	protected static $_global_data = array();

	protected static function capture($view_filename, array $view_data)
	{
		// Some code here
	}

}</code></pre>

		<h5 id="variables">Variables</h5>

		<p>Variable names should be concise, and contain only lower case letters and underscores. Loop iterators should
			be short, preferably a single character.</p>

<pre class="php"><code>$first_name
$buffer
for ($i = 0; $i < $max; $i++)</code></pre>

		<h5 id="constants">Constants</h5>

		<p>Constants follow the same guide lines as variables, with the exception that constants should be all upper
			case.</p>

<pre class="php"><code>MY_CONSTANT
TEMPLATE_PATH
TEXT_DEFAULT</code></pre>

		<h3 id="keywords">Keywords</h3>

		<p>Keywords such as true, false, null, as, etc should be all lower case, as upper case is reserved for
			constants. Same goes for primitive types like array, integer, string.</p>

<pre class="php"><code>$var = true;
$var = false;
$var = null;
foreach ($array as $key => $value)
public function my_function(array $array)
function my_function($arg = null)</code></pre>

		<h3 id="control_structures">Control Structures</h3>

		<p>The structure keywords such as if, for, foreach, while, switch should be followed by a space as should
			parameter/argument lists and values. Braces should be placed on a new line, and break should have the same
			tab as its case.</p>

<pre class="php"><code>if ($arg === true)
{
	//do something here
}
elseif ($arg === null)
{
	//do something else here
}
else
{
	//catch all do something here
}
foreach ($array as $key => $value)
{
	//loop here
}
for ($i = 0; $i < $max; $i++)
{
	//loop here
}
while ($i < $max)
{
	//loop here
}
switch ($var)
{
	case 'value1':
		//do something here
	break;
	default :
		//do something here
	break;
}</code></pre>

		<h3 id="comparison_logical">Comparisons, Logical operators</h3>

		<p>Comparing function/method returns and variables should be type aware, for example some functions may return
			false, and when comparing this return the type sensitive operators such as === or !==. Additionally, use of
			and or or is preferred over && or || for readability. In some cases this cannot be avoided and the use of
			&& or || as its required may be used. The ! should have spaces on both sides when used.</p>

<pre class="php"><code>if ($var == false and $other_var != 'some_value')
if ($var === false or my_function() !== false)
if ( ! $var)</code></pre>

		<h5 id="class_interface">Class/Interface Declarations</h5>

		<p>Class/interface declarations have the opening brace on the same line:</p>

<pre class="php"><code>class Session {

}</code></pre>

		<h5 id="function_method">Function/Method Declarations</h5>

		<p>The function/method opening brace must always begin on a new line and have the same indentation as its
			structure.</p>

<pre class="php"><code>class Session {

	public static function get_flash($name, $data)
	{
		// Some code here
	}

}</code></pre>

		<h5 id="variables">Variables</h5>

		<p>When initializing variables, one variable should be declared per line. To enhance code readability these
			should each be on a separate line. Align values and comments when appropriate.</p>

<pre class="php"><code>$var        = ''; // do each on its own line
$other_var  = ''; // do each on its own line</code></pre>

		<h5 id="brackets_parenthesis">Brackets and Parenthesis</h5>

		<p>No space should come before or after the initial bracket/parenthesis. There should not be a space before closing bracket/parenthesis.</p>

<pre class="php"><code>$array = array(1, 2, 3, 4);
$array['my_index'] = 'something';
for ($i = 0; $i < $max; $i++)</code></pre>

		<h5 id="concatenation">Concatenation</h5>

		<p>String concatenation should not contain spaces around the joined parts</p>

<pre class="php"><code>//yes
$string = 'my string '.$var.' the rest of my string';

//no
$string = 'my string ' . $var . ' the rest of my string';</code></pre>

		<h5 id="operators">Operators</h5>

<pre class="php"><code>$var = 'something';
if ($var == 'something') //space before and after operator
$var++; // no space before
++$var; //no space after
$var = $some_var + $other_var; //space before and after operator</code></pre>

	</section>

	<section id="footer">
		<p>
			<a href="http://fuelphp.com">Fuel</a> is released under the MIT license.<br />
			&copy; 2010 - 2011 Fuel Development Team
		</p>
	</section>

</body>
</html>
